/**
 * 通用数据模型定义
 * 
 * 用于框架中的数据结构定义，支持多种数据类型。
 * 这些接口和枚举定义了应用中常用的数据结构，
 * 包括用户、产品、文章等实体模型，以及API响应、
 * 分页、表单等通用数据结构。
 * 
 * @fileoverview 数据模型定义文件
 * @author HarmonyOS开发团队
 * @version 1.0.0
 */

// 通用数据模型定义
// 用于框架中的数据结构定义，支持多种数据类型

/**
 * 基础数据项接口
 * 
 * 定义了所有数据项的通用属性，作为其他数据接口的基础。
 * 所有数据模型都应该继承此接口以确保基本属性的一致性。
 */
export interface BaseDataItem {
  id: string;          // 唯一标识
  title: string;       // 标题
  description: string; // 描述
  imageUrl?: string;   // 图片链接（可选）
  timestamp?: string;  // 时间戳（可选）
}

/**
 * 用户状态枚举
 * 
 * 定义了用户在系统中的可能状态。
 * 用于控制用户访问权限和显示状态。
 */
export enum UserStatus {
  ACTIVE = 'active',     // 活跃状态
  INACTIVE = 'inactive', // 非活跃状态
  SUSPENDED = 'suspended' // 暂停状态
}

/**
 * 用户数据接口
 * 
 * 继承自BaseDataItem，扩展了用户特有的属性。
 * 用于表示系统中的用户信息，包括基本信息和状态。
 */
export interface UserData extends BaseDataItem {
  name: string;        // 用户名
  email: string;       // 邮箱
  phone?: string;      // 电话（可选）
  avatar?: string;     // 头像（可选）
  status: UserStatus;  // 用户状态
}

/**
 * 产品数据接口
 * 
 * 继承自BaseDataItem，扩展了产品特有的属性。
 * 用于表示电商或产品管理系统中的产品信息。
 */
export interface ProductData extends BaseDataItem {
  price: number;        // 价格
  category: string;     // 分类
  stock: number;        // 库存
  rating?: number;      // 评分（可选）
  tags?: string[];      // 标签（可选）
}

/**
 * 文章数据接口
 * 
 * 继承自BaseDataItem，扩展了文章特有的属性。
 * 用于表示博客、新闻或内容管理系统中的文章信息。
 */
export interface ArticleData extends BaseDataItem {
  author: string;       // 作者
  content: string;      // 内容
  publishDate: string;  // 发布日期
  readTime: number;     // 阅读时间（分钟）
  category: string;     // 分类
  views?: number;       // 浏览量（可选）
  likes?: number;       // 点赞数（可选）
}

/**
 * API响应接口
 * 
 * 定义了统一的API响应格式，用于前后端数据交互。
 * 使用泛型T来支持不同类型的响应数据。
 * 
 * @template T 响应数据的类型
 */
export interface ApiResponse<T> {
  code: number;         // 响应码
  message: string;      // 响应消息
  data: T;             // 响应数据
  timestamp: string;   // 响应时间戳
  error?: ErrorInfo;   // 错误信息（可选）
}

/**
 * 错误信息接口
 * 
 * 定义了API响应中的错误信息结构，用于传递详细的错误信息。
 */
export interface ErrorInfo {
  code: string;        // 错误码
  message: string;     // 错误消息
  details?: any;       // 错误详情（可选）
  field?: string;      // 错误字段（可选，用于表单验证错误）
}

/**
 * 分页请求参数
 * 
 * 定义了分页查询的请求参数，用于服务器端分页功能。
 * 支持关键词搜索、排序等常用功能。
 */
export interface PageRequest {
  page: number;         // 页码
  pageSize: number;     // 每页大小
  keyword?: string;     // 搜索关键词（可选）
  sortBy?: string;      // 排序字段（可选）
  sortOrder?: 'asc' | 'desc'; // 排序方向（可选）
}

/**
 * 分页响应数据
 * 
 * 定义了分页查询的响应格式，包含数据列表和分页信息。
 * 使用泛型T来支持不同类型的数据列表。
 * 
 * @template T 列表项的数据类型
 */
export interface PageResponse<T> {
  list: T[];           // 数据列表
  total: number;       // 总记录数
  page: number;        // 当前页码
  pageSize: number;    // 每页大小
  totalPages: number;  // 总页数
}

/**
 * 表单字段配置
 * 
 * 定义了动态表单字段的配置结构，用于构建灵活的表单系统。
 * 支持多种字段类型、验证规则和自定义选项。
 */
export interface FormField {
  name: string;        // 字段名
  label: string;       // 字段标签
  type: 'text' | 'number' | 'email' | 'password' | 'select' | 'checkbox' | 'radio' | 'date'; // 字段类型
  placeholder?: string; // 占位符
  required?: boolean;  // 是否必填
  options?: Array<{ label: string; value: string }>; // 选项（用于select、radio等）
  defaultValue?: any;  // 默认值
  validation?: {       // 验证规则
    pattern?: string;  // 正则表达式
    min?: number;      // 最小值/最小长度
    max?: number;      // 最大值/最大长度
    message?: string;  // 错误消息
  };
}

/**
 * 表单数据接口
 * 
 * 定义了动态表单数据的结构，使用索引签名支持任意字段。
 * 用于存储表单提交的数据。
 */
export interface FormData {
  [key: string]: any;  // 动态表单数据
}

/**
 * 数据表格列配置
 * 
 * 定义了数据表格列的配置结构，用于构建灵活的表格组件。
 * 支持自定义渲染、排序和过滤功能。
 */
export interface TableColumn {
  key: string;         // 列键
  title: string;       // 列标题
  width?: number;      // 列宽
  sortable?: boolean;  // 是否可排序
  filterable?: boolean; // 是否可过滤
  render?: (value: any, record: any) => string; // 自定义渲染函数
}

/**
 * 图表数据点
 * 
 * 定义了图表中单个数据点的结构，用于构建各种类型的图表。
 * 支持自定义标签、值和颜色。
 */
export interface ChartDataPoint {
  label: string;       // 标签
  value: number;       // 值
  color?: string;      // 颜色（可选）
}

/**
 * 图表配置
 * 
 * 定义了图表的完整配置结构，用于构建灵活的图表组件。
 * 支持多种图表类型和自定义配置选项。
 */
export interface ChartConfig {
  type: 'line' | 'bar' | 'pie' | 'scatter'; // 图表类型
  title: string;       // 图表标题
  data: ChartDataPoint[]; // 图表数据
  xAxis?: string;      // X轴标签
  yAxis?: string;      // Y轴标签
  showLegend?: boolean; // 是否显示图例
}